The TADS Alternate Library
Version 2.0
Coding Conventions
Copyright 2000 by Kevin Forchione.
This is part of the TADS Alternate Library Authors Manual.
Introduction and Table of Contents
Naming Conventions
Alt adopts fairly strict
Java-style coding conventions with few exceptions. Following these standards helps
ensure that an author will not be caught out by the case-sensitive nature of
the TADS compiler. Previous libraries suffered from certain inconsistencies
with regard to naming conventions that caused inadvertent programming errors
because of TADS lack of strict type checking. Following these conventions
should make it easier for an author to avoid this kind of error.
Files
Alt is broken up into five
categories of files: header, class, function, object, and grammar. The naming convention
for files is that the file has the name of the object, class, function, or
grammar class it defines. The name is in all lower-case with multiple word
names running together as one word, for example: isindistinguishable.t. Header,
class, and grammar files all have the ‘.h’ file extension, while function and
object files end in the ‘.t’ file extension.
Exceptions: none
#defines
Symbols used in the
#defines for determination of file #inclusion appear in all uppercase preceding
and ending with an underscore, and with each capitalised word of the definition
name separated by an underscore. The name of the #defined symbol should contain
the file-type suffix. For example for KeyedLockable class the #define is
_KEYED_LOCKABLE_H_, and for the global object the #define is _GLOBAL_T_.
Exceptions: none
By convention class names
begin with an uppercase letter. If the class name consists of more than one
word, such as FixedItem the words are joined together and each word after the
first begins with an uppercase letter.
Exceptions: none
By convention function
names begin with a lowercase letter. If the function name consists of more than
one word, such as listContCont() the words are joined together and each word
after the first begins with an uppercase letter.
Exceptions: none
By convention method names
begin with a lowercase letter. If the method name consists of more than one
word, such as listContCont() the words are joined together and each word after the
first begins with an uppercase letter.
Special Note:
Description methods are
somewhat problematic in that they may be invoked by the TADS 2 built-in parser
for use in its message construction and display. Therefore the following
description methods are defined in Thing class and are used as parser hooks for
their Alt equivalents:
adesc, multisdesc,
pluraldesc, prefixdesc, sdesc, thedesc
These should not be coded
in your game object definitions.
See also: Verification and Action Methods
The TADS 2 compiler
generates ver-, do-, and io- prefixes for method names. The
standard for verb method naming follows that recommended by the TADS Authors
manual. The first letter of the value defined for the verb’s doAction and ioAction
properties is always capitalised. This ensures that the name of the generated
verification and action method follows Alt method naming standards.
For example:
takeVerb:
DeepVerb
//
code not shown
doAction
= ‘Take’
//
code not shown
;
Because of the variable
number of arguments passed to verification and action methods: actor; actor and
direct-object; actor and indirect-object, dependent upon the verb template
specified by the verb definition the convention specified in Case I has long been
used by TADS authors as a mnemonic. Case I verification and action method
names, with few exceptions, do not comply with Alt method naming
standards.
For completeness we
document the case II verification and action method naming standards, which
fully conform to the more general Alt method naming standards.
Verbs that take the form:
verb preposition direct-object
verb direct-object preposition
should not capitalise the preposition
in their doAction property, to indicate that this verb uses a preposition but
does not expect an indirect-object:
getOnVerb:
DeepVerb
//
code not shown
doAction
= ‘Geton’
//
code not shown
;
Method names for this form
would then be:
verDoGeton()
{…}
doGeton()
{…}
Exceptions That Comply
with Alt Standards:
[The following exceptions
to the above rule comply with Alt naming stands for method names ]
Direction prepositions.
Since some of the direction prepositions are one-letter values, such as n, s,
e, and w names involving direction prepositions capitalise the first letter of
the preposition or both letters in the case of abbreviations, such as NE, SW,
etc. For example: verDoMoveN(), doMoveSW, and verDoClimbDown().
Verbs that take the form:
verb direct-object preposition indirect-object
verb indirect-object direct-object
should capitalise the
first letter of the preposition in their verb’s ioAction() property. For
example:
throwVerb:
DeepVerb
//
code not shown
ioAction(atPrep)
= ‘ThrowAt’
//
code not shown
;
Method names for this form
would then be:
verDoThrowAt()
{…}
verIoThrowAt()
{…}
ioThrowAt()
{…}
Exceptions: none
By convention function
names begin with a lowercase letter. If the function name consists of more than
one word, such as newPlayer the words are joined together and each word after
the first begins with an uppercase letter. Typically the argument name
represents the type of variable expected by the function or method. For
example: listCont(obj), switchPlayer(newPlayer).
Exceptions: none
By convention attribute
and local variable names begin with a lowercase letter. If the attribute or local
variable name consists of more than one word, such as maxBulk the words are
joined together and each word after the first begins with an uppercase letter.
Note that while Java
conventions use a- and an- prefixes to argument names this is not enforced in
Alt.
Exceptions: none
By convention object names
begin with a lowercase letter (note, Me is an exception). If the object name
consists of more than one word, such as gameClock the words are joined together
and each word after the first begins with an uppercase letter.
Alt defines the Me,
numObj, and strObj objects as required by TADS 2 compiler and built-in
parser.
Exceptions: Me
Bracing conventions help make
the code easier to read. Alt adopts the convention of putting the brace for the
beginning of a function or method on the same line with the declaration as
illustrated below:
listCont(obj)
{
//
function coding
}
contentsVisible
= { return self.isOpen; }
The following style is
used for if-then-else, for-next, and while-looping:
if
(condition) {
statements;
} else {
statements;
}
for (i =
1; i <= n; ++i) {
}
do {
} while(
o )
while( o ) {
}